Overview

The SourceSync Client API provides a streamlined interface for managing your media productions, distributions, and activations. This RESTful API uses API key authentication and follows consistent patterns to make integration straightforward and reliable.

Base URLs

• Production: https://platform.sourcesync.io
• Development: https://platform-dev.sourcesync.io

Authentication

All requests require an API key passed in the X-API-Key header. API keys follow this format:

app.v1.[unique-identifier]

Example:

X-API-Key: app.v1.your-api-key-here

Each API key is associated with a specific organization and inherits its permissions and access rights. The key automatically filters all requests to only show and modify content within your organization's scope.

Verifying Your API Key

Before making other API calls, you can verify your API key and get its associated information:

GET /key

Response example:

{
  "name": "Production Access Key",
  "settings": {
    "defaults": {
      "property": "123"
    }
  },
  "value": {
    "componentName": "context1"
  },
  "organization": "1de71807-b64b-4398-96fa-a0ac67c727d9",
  "legacy_org_id": 1,
  "vidvita_org_id": 114
}

Core Concepts

Organizations and Properties

• Each API key is tied to a specific organization
• Organizations can have multiple properties
• Content (productions, distributions, activations) belongs to properties within your organization

Content Types

1. Productions: The root content type representing a media production
2. Distributions: Ways to distribute your production content
3. Activations: Specific instances or campaigns for your distributions

Response Format

All API responses follow a consistent format:

{
  "status": "success",
  "data": [
    // Response data here
  ]
}

Error responses:

{
  "status": "error",
  "error": {
    "message": "Error description here"
  }
}

Working with Productions

Productions are the foundation of your content in SourceSync. They represent the base media assets and metadata that can be distributed and activated.

Listing Productions

GET /productions

Use this to get a list of all productions your API key has access to. The response includes basic metadata about each production.

Creating a Production

POST /productions
Content-Type: application/json

[{
    "name": "My New Production",
    "settings": {
        "key": "value"
    }
}]

Important notes:

• The request body must be an array, even for single items
• The name field is required
• settings is an optional object for custom configuration
• The production will automatically be associated with your organization

Updating a Production

Individual update:

PATCH /productions/{id}
Content-Type: application/json

{
    "name": "Updated Production Name",
    "settings": {
        "key": "new value"
    }
}

Batch update:

PATCH /productions
Content-Type: application/json

[{
    "id": "123",
    "name": "Updated Production Name"
}]

Deleting a Production

Individual delete:

DELETE /productions/{id}

Batch delete:

DELETE /productions

[{
    "id": "123"
}]

Working with Distributions

Distributions represent different ways to package and deliver your production content. A single production can have multiple distributions for different platforms or purposes.

Creating a Distribution

POST /productions/{productionId}/distributions
Content-Type: application/json

[{
    "name": "Web Distribution",
    "settings": {
        "format": "HLS",
        "quality": "adaptive"
    }
}]

Managing Distributions

The API provides similar endpoints for managing distributions as productions:

• GET /productions/{productionId}/distributions - List distributions
• PATCH /productions/{productionId}/distributions/{id} - Update a distribution
• DELETE /productions/{productionId}/distributions/{id} - Delete a distribution

Working with Activations

Activations represent specific instances where your content is being used. They can include campaign details, scheduling, and tracking information.

Creating an Activation

POST /productions/{productionId}/activations
Content-Type: application/json

[{
    "name": "Holiday Campaign 2024",
    "settings": {
        "startDate": "2024-12-01",
        "endDate": "2024-12-31",
        "targeting": {
            "regions": ["NA", "EU"],
            "platforms": ["web", "mobile"]
        }
    }
}]

Managing Activations

Similar to distributions, you can manage activations with these endpoints:

• GET /productions/{productionId}/activations - List activations
• PATCH /productions/{productionId}/activations/{id} - Update an activation
• DELETE /productions/{productionId}/activations/{id} - Delete an activation

Best Practices

1. API Key Management

   • Keep your API keys secure
   • Use different keys for development and production
   • Regularly rotate keys for security

2. Error Handling

   • Always check the response status
   • Implement retry logic for network failures
   • Handle rate limits gracefully

3. Batch Operations

   • Use batch endpoints when modifying multiple items
   • Keep batch sizes reasonable (recommended max: 100 items)

4. Property Management

   • Set default properties in your API key settings
   • Verify property access before operations

Rate Limits and Quotas

• Standard rate limit: 1000 requests per minute
• Batch operations count as one request
• Contact support for higher limits

Common Errors and Solutions

Error Code	Description	Solution
401	Invalid API key	Verify your API key and its format
403	Insufficient permissions	Check your organization and property access
404	Resource not found	Verify the ID exists and you have access
429	Rate limit exceeded	Implement backoff and retry logic

Webhooks and Notifications

The API supports webhooks for real-time updates. Configure these through your account settings to receive notifications about:

• Content status changes
• Distribution updates
• Activation triggers

Support and Resources

• Technical Support: support@sourcesync.io
• API Status: status.sourcesync.io
• Developer Community: community.sourcesync.io

Version History

Current Version: 1.0.0

• Initial release with core functionality
• Productions, Distributions, and Activations support
• Batch operations support